# 板型与硬件配置

```{admonition} 本文引用的文件
:class: note

- `mpython/mpconfigboard.h`
- `mpython-classroom-kit/mpconfigboard.h`
- `labplus_classroom_kit_II/mpconfigboard.h`
- `labplus_1956/mpconfigboard.h`
- `labplus-experiment-box-2024/mpconfigboard.h`
- `GENERIC/mpconfigboard.h`
- `mpython/modules/mpython.py`
- `mpython-classroom-kit/modules/mpython.py`
- `labplus_classroom_kit_II/modules/mpython.py`
- `labplus_1956/modules/mpython.py`
- `labplus-experiment-box-2024/modules/mpython.py`
- `builtins/modmotion.c`
- `builtins/machine_touchpad.c`
- `builtins/machine_pin.c`
```

## 产品概述
本仓库的固件移植层（firmware/port）为 mPython 掌控板生态提供多板型支持，覆盖标准掌控板、课堂套件、实验箱等场景。通过“板型目录 + 配置文件 + 模块映射”的方式，将同一套 MicroPython 运行时适配到不同硬件：每个板型在 port/boards/<board>/ 下拥有独立的 mpconfigboard.h（声明板名、MCU、内置外设开关、内建模块映射）和 modules/（板级 Python 库入口与扩展）。本文聚焦于 ESP32 平台的 6 种板型：mpython、mpython-classroom-kit、labplus_classroom_kit_II、labplus_1956、labplus-experiment-box-2024、GENERIC，梳理其硬件差异、配置文件要点与模块映射关系，帮助开发者快速定位目标板型的可用能力与差异点。

## 核心业务流程
- 构建期选择板型：通过 CMake/构建脚本指定 board 目录，编译时加载对应 mpconfigboard.h，注册该板的名称、MCU、内置外设开关以及 BOARD_PORT_BUILTIN_MODULES 映射表。
- 运行期模块加载：MicroPython 启动后根据板型配置启用或禁用特定 C 级 builtins 模块；Python 层 modules/ 下的 mpython.py 作为统一 API 入口，封装按键、触摸、传感器、显示、网络等能力，屏蔽底层差异。
- 应用调用路径：用户代码 import mpython → mpython.py 内部依赖 machine_pin/machine_touchpad/modmotion 等 builtins 与驱动，暴露一致 API；不同板型通过各自 modules/mpython.py 与 BOARD_PORT_BUILTIN_MODULES 的差异实现差异化功能。

```text
flowchart TD
A["构建系统<br/>选择板型目录"] --> B["加载 mpconfigboard.h<br/>设置板名/MCU/外设开关"]
B --> C["注册 BOARD_PORT_BUILTIN_MODULES<br/>绑定C级模块到Python名字空间"]
C --> D["MicroPython运行时初始化"]
D --> E["导入板级 mpython.py<br/>暴露统一API"]
E --> F["应用代码调用<br/>按键/触摸/传感器/显示/网络"]
```

**章节来源**
- `mpython/mpconfigboard.h:1-22`
- `mpython-classroom-kit/mpconfigboard.h:1-26`
- `labplus_classroom_kit_II/mpconfigboard.h:1-21`
- `labplus_1956/mpconfigboard.h:1-25`
- `labplus-experiment-box-2024/mpconfigboard.h:1-21`
- `GENERIC/mpconfigboard.h:1-4`

## 功能模块清单
- 通用能力（跨板型）
  - Pin 控制：machine_pin.c 提供数字/模拟/PWM 引脚抽象，各板型复用。
  - 触摸输入：machine_touchpad.c 提供触摸键能力，用于板载触摸按键。
  - 运动传感：modmotion.c 提供加速度计/陀螺仪/磁力计统一接口，部分板型通过 BOARD_PORT_BUILTIN_MODULES 显式注册。
- 板型专属能力
  - mpython（标准掌控板）：启用 ADC/DAC，modules/mpython.py 提供 OLED、WiFi、MOTION、Pin/Button/Touch/Light/Sound 等统一 API。
  - mpython-classroom-kit：关闭 ADC/DAC，显式注册 motion_mpu6050 与 rgbLED5x5 模块，适合课堂套件教学。
  - labplus_classroom_kit_II：启用 ADC/DAC，modules/ 包含电机、超声波等教学扩展。
  - labplus_1956：启用 ADC/DAC，显式注册 motion_mpu6050，modules/ 包含 K210/AI 相关扩展。
  - labplus-experiment-box-2024：启用 ADC/DAC，modules/ 包含摄像头与 V831 相关扩展。
  - GENERIC：最小化配置，仅声明板名与 MCU，适用于通用 ESP32 模块开发。

```text
graph TB
subgraph "C级内置模块"
MP["machine_pin.c"]
TP["machine_touchpad.c"]
MM["modmotion.c"]
end
subgraph "板型配置"
B1["mpython"]
B2["mpython-classroom-kit"]
B3["labplus_classroom_kit_II"]
B4["labplus_1956"]
B5["labplus-experiment-box-2024"]
B6["GENERIC"]
end
subgraph "Python层入口"
PY1["mpython/modules/mpython.py"]
PY2["mpython-classroom-kit/modules/mpython.py"]
PY3["labplus_classroom_kit_II/modules/mpython.py"]
PY4["labplus_1956/modules/mpython.py"]
PY5["labplus-experiment-box-2024/modules/mpython.py"]
end
B1 --> PY1
B2 --> PY2
B3 --> PY3
B4 --> PY4
B5 --> PY5
B6 --> |"无专用modules"| MP
MP --> PY1
TP --> PY1
MM --> PY1
```

**图表来源**
- `mpython/mpconfigboard.h:1-22`
- `mpython-classroom-kit/mpconfigboard.h:1-26`
- `labplus_classroom_kit_II/mpconfigboard.h:1-21`
- `labplus_1956/mpconfigboard.h:1-25`
- `labplus-experiment-box-2024/mpconfigboard.h:1-21`
- `GENERIC/mpconfigboard.h:1-4`
- `mpython/modules/mpython.py`
- `mpython-classroom-kit/modules/mpython.py`
- `labplus_classroom_kit_II/modules/mpython.py`
- `labplus_1956/modules/mpython.py`
- `labplus-experiment-box-2024/modules/mpython.py`
- `builtins/machine_pin.c`
- `builtins/machine_touchpad.c`
- `builtins/modmotion.c`

**章节来源**
- `mpython/mpconfigboard.h:1-22`
- `mpython-classroom-kit/mpconfigboard.h:1-26`
- `labplus_classroom_kit_II/mpconfigboard.h:1-21`
- `labplus_1956/mpconfigboard.h:1-25`
- `labplus-experiment-box-2024/mpconfigboard.h:1-21`
- `GENERIC/mpconfigboard.h:1-4`
- `mpython/modules/mpython.py`
- `mpython-classroom-kit/modules/mpython.py`
- `labplus_classroom_kit_II/modules/mpython.py`
- `labplus_1956/modules/mpython.py`
- `labplus-experiment-box-2024/modules/mpython.py`
- `builtins/machine_pin.c`
- `builtins/machine_touchpad.c`
- `builtins/modmotion.c`

## 数据与状态
- 板型标识与MCU
  - 所有板型均声明 MICROPY_HW_BOARD_NAME 与 MICROPY_HW_MCU_NAME，用于运行时识别与日志输出。
- 内置外设开关
  - ADC/DAC：mpython、labplus_classroom_kit_II、labplus_1956、labplus-experiment-box-2024 开启；mpython-classroom-kit 关闭；GENERIC 未显式定义。
- 内建模块映射（BOARD_PORT_BUILTIN_MODULES）
  - mpython-classroom-kit：显式注册 motion_mpu6050 与 rgbLED5x5。
  - labplus_1956：显式注册 motion_mpu6050。
  - 其他板型：未在此文件中追加额外映射，使用默认内置集合。
- Python 层 API 入口
  - 各板型 modules/mpython.py 提供统一 API（如 MOTION、Pin、Button、Touch、wifi 等），屏蔽底层差异；不同板型可在此基础上扩展或裁剪能力。

```text
classDiagram
class 板型配置 {
+板名
+MCU
+ADC/DAC开关
+内建模块映射
}
class Python入口 {
+统一API
+板级扩展
}
class C级内置 {
+Pin控制
+触摸输入
+运动传感
}
板型配置 --> Python入口 : "modules/mpython.py"
Python入口 --> C级内置 : "依赖"
```

**图表来源**
- `mpython/mpconfigboard.h:1-22`
- `mpython-classroom-kit/mpconfigboard.h:1-26`
- `labplus_classroom_kit_II/mpconfigboard.h:1-21`
- `labplus_1956/mpconfigboard.h:1-25`
- `labplus-experiment-box-2024/mpconfigboard.h:1-21`
- `GENERIC/mpconfigboard.h:1-4`
- `mpython/modules/mpython.py`
- `mpython-classroom-kit/modules/mpython.py`
- `labplus_classroom_kit_II/modules/mpython.py`
- `labplus_1956/modules/mpython.py`
- `labplus-experiment-box-2024/modules/mpython.py`
- `builtins/machine_pin.c`
- `builtins/machine_touchpad.c`
- `builtins/modmotion.c`

**章节来源**
- `mpython/mpconfigboard.h:1-22`
- `mpython-classroom-kit/mpconfigboard.h:1-26`
- `labplus_classroom_kit_II/mpconfigboard.h:1-21`
- `labplus_1956/mpconfigboard.h:1-25`
- `labplus-experiment-box-2024/mpconfigboard.h:1-21`
- `GENERIC/mpconfigboard.h:1-4`
- `mpython/modules/mpython.py`
- `mpython-classroom-kit/modules/mpython.py`
- `labplus_classroom_kit_II/modules/mpython.py`
- `labplus_1956/modules/mpython.py`
- `labplus-experiment-box-2024/modules/mpython.py`

## 关键约束与边界
- 板型选择约束
  - 构建时必须明确指定 board 目录，否则无法正确加载 mpconfigboard.h 与 modules/ 入口。
- 外设可用性约束
  - ADC/DAC 在不同板型上可能被关闭（如 classroom-kit），导致依赖这些通道的传感器不可用。
  - 某些板型需显式注册 motion_mpu6050 与 rgbLED5x5，否则 Python 层无法访问对应能力。
- 模块映射边界
  - BOARD_PORT_BUILTIN_MODULES 仅影响 C 级模块的 Python 可见性；Python 层 mpython.py 的 API 仍可能因板型差异而裁剪或扩展。
- 通用性与兼容性
  - GENERIC 板型最小化配置，适合通用 ESP32 模块；若需完整 mPython 体验，应选用带 modules/mpython.py 的具体板型。

**章节来源**
- `mpython-classroom-kit/mpconfigboard.h:1-26`
- `labplus_1956/mpconfigboard.h:1-25`
- `mpython/mpconfigboard.h:1-22`
- `labplus_classroom_kit_II/mpconfigboard.h:1-21`
- `labplus-experiment-box-2024/mpconfigboard.h:1-21`
- `GENERIC/mpconfigboard.h:1-4`